home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / System / XADmaster / xad_dev / Sources / clients / xadIO.doc < prev    next >
Encoding:
Text File  |  2001-04-01  |  14.6 KB  |  426 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadIO/--general--
  4. xadIO/--Why use it--
  5. xadIO/--The sourcecode--
  6. xadIO/xadIOAlloc
  7. *xadIO/xadIODropBitsHigh
  8. *xadIO/xadIODropBitsLow
  9. *xadIO/xadIOGetBitsHigh
  10. *xadIO/xadIOGetBitsLow
  11. *xadIO/xadIOGetChar
  12. *xadIO/xadIOPutChar
  13. *xadIO/xadIOReadBitsHigh
  14. *xadIO/xadIOReadBitsLow
  15. xadIO/xadIOWriteBuf
  16. xadIO/xio_GetFunc
  17. xadIO/xio_InFunc
  18. xadIO/xio_OutFunc
  19. xadIO/xio_PutFunc
  20.  
  21. VERSION
  22.         $VER: xadIO.doc 1.0 (24.03.2001) by SDI
  23.  
  24. xadIO/--general--                                           xadIO/--general--
  25.  
  26.     How to use this xadIO-system? It is very easy. The callers side does
  27.     not known anything about the algorithm except its name.
  28.     An example call may look like this:
  29.  
  30.     struct xadInOut *io;
  31.  
  32.       if((io = xadIOAlloc(XADIOF_ALLOCINBUFFER|XADIOF_ALLOCOUTBUFFER
  33.       |XADIOF_NOCRC16, ai, xadMasterBase)))
  34.     {
  35.           io->xio_InSize = fi->xfi_CrunchSize;
  36.       io->xio_OutSize = fi->xfi_Size;
  37.           io->xio_CRC32 = ~0;
  38.  
  39.           switch(method)
  40.           {
  41.           case METHOD1: err = decrunchM1(io); break;
  42.           case METHOD2: err = decrunchM2(io); break;
  43.           case STORED: 
  44.             while(!(io->xio_Flags & (XADIOF_LASTOUTBYTE|XADIOF_ERROR)))
  45.               xadIOPutChar(io, xadIOGetChar(io));
  46.             err = io->xio_Error;
  47.             break;
  48.           default: err = XADERR_DATAFORMAT;
  49.           }
  50.  
  51.           if(!err)
  52.             err = xadIOWriteBuf(io);
  53.           if(!err && ~io->xio_CRC32 != crc)
  54.             err = XADERR_CHECKSUM;
  55.           xadFreeObjectA(io, 0);
  56.         }
  57.         else
  58.           err = XADERR_NOMEMORY;
  59.  
  60.     This easy structure can be expanded a lot. So it maybe necessary to
  61.     replace the xio_PutFunc() to do inline RunLength decoding or add input
  62.     and output functions for decryption and different checksum
  63.     calculations. All this is possible and very easy.
  64.     The STORED method shows an example how to copy the contents of the
  65.     file only. Normally the XADAC_COPY method should be used for that.
  66.     In case of password decryption or nonstandard checksum calculation,
  67.     the above is an easy way to do this in the same unique interface as
  68.     the decompression.
  69.  
  70.     The decompressors side does not know about this specials and only
  71.     does it work. Its side looks like that:
  72.  
  73.     static LONG decrunchM1(struct xadInOut *io)
  74.         {
  75.           struct priv *dat;
  76.           struct xadMasterBase *xadMasterBase = io->xio_xadMasterBase;
  77.  
  78.           if((dat = (struct priv *) xadAllocVec(sizeof(struct priv),
  79.           MEMF_CLEAR|MEMF_PUBLIC)))
  80.           {
  81.             /* init stuff */
  82.  
  83.             while(!(io->xio_Flags & (XADIOF_LASTOUTBYTE|XADIOF_ERROR)))
  84.             {
  85.               /* do something, use xadIOGetChar() and xadIOPutChar()
  86.                  or better use the bit functions if possible. */
  87.               /* Error codes are set in io->xio_Error TOGETHER with
  88.                  setting the flag XADIOF_ERROR. */
  89.             }
  90.             xadFreeObjectA(dat, 0);
  91.           }
  92.           return io->xio_Error;
  93.         }
  94.  
  95.     It maybe ncessary to add additionally arguments to the function call
  96.     (e.g. the number of bits or global bufferes for multifile compression
  97.     like in LZX). Generally it is best, if nothing of this is needed and
  98.     the algorithm allocates its bufferes itself. This makes reusing it
  99.     much easier.
  100.  
  101. xadIO/--Why use it--                                     xadIO/--Why use it--
  102.  
  103.     This system is very open and allows support of different decompression
  104.     routines.
  105.  
  106.     Some things, which are possible:
  107.     - The Input/Output functions maybe changed to calculate checksums,
  108.       encrypt, decrypt the data or even do another decompression step
  109.       (e.g. run length decoding) directly.
  110.     - The interface can be used to decrunch from file to file, from file
  111.       to memory, from memory to memory or from memory to file without any
  112.       additional work in the decrunching function.
  113.     - The system is not direct part of the xadmaster.library to make it
  114.       much faster (no system call interface inbetween. The functions are
  115.       really fast, but speed maybe improved by inlining the bits
  116.       functions directly. The source code provides mechanisms to do so.
  117.  
  118.     Thoughts about the implementation:
  119.     - The xadIOPutChar and xadIOGetChar interfaces aren't optimal when
  120.       compared to buffer based algorithms and anything like that. But
  121.       when doing tests the speed decrease is not really a problem.
  122.       This is because the put and get operations aren't most important
  123.       in modern compression algorithms anymore.
  124.     - The main advantage is an easy to use and powerful interface, which
  125.       is as fast as most other interfaces. And it is a standardized
  126.       interface.
  127.     - The reliability of the program code is increased when doing changes,
  128.       as often the code itself needs no modifications, but only new ways
  129.       to call (e.g. with CRC call, ...) are needed.
  130.     - It is very easy to reuse the algorithms (and most time algorithms
  131.       are used in different archiver systems).
  132.  
  133. xadIO/--The sourcecode--                             xadIO/--The sourcecode--
  134.  
  135.     The source code consists of 2 files called xadIO.h and xadIO.c.
  136.  
  137.     In case you want to use it as link library, call the file xadIO.h
  138.     from your sources always. This is like for any other module in your
  139.     projects.
  140.     The link library is produces, when compiling the file xadIO.c with
  141.     the define XADIOFUNCMODE defined to "".
  142.  
  143.     The other way is calling xadIO.c from your source code. In this case
  144.     the functions default to be static and this maybe inlined in your
  145.     code. Defining the XADIOFUNCMODE to anything else than static may
  146.     change the type of the functions xadIOAlloc() and xadIOWriteBuf().
  147.     Changing XADIOFUNCMODEBITS allows you to change the bit functions
  148.     (e.g. make the inline functions). This define default to the value
  149.     of XADIOFUNCMODE normally.
  150.     You need to enable the required bit-functions in this mode. Define
  151.     following before calling the source file:
  152.     XADIOGETBITSHIGH
  153.     XADIOGETBITSLOW
  154.     XADIOREADBITSHIGH
  155.     XADIOREADBITSLOW
  156.  
  157. xadIO/xadIOAlloc                                             xadIO/xadIOAlloc
  158.  
  159.     NAME
  160.         xadIOAlloc - Allocate the xadInOut structure and necessary buffers
  161.  
  162.     SYNOPSIS
  163.         struct xadInOut * xadIOAlloc(ULONG flags, struct xadArchiveInfo *ai,
  164.                                      struct xadMasterBase *xadMasterBase)
  165.  
  166.     FUNCTION
  167.         This function allocates the xadInOut structure and initializes it.
  168.         Also required buffers are allocated.
  169.         The allocated structure is afterwards freed with xadFreeObjectA().
  170.         
  171.         The flags allow to change the behaviour of this function and other
  172.         functions of this system.
  173.  
  174.     XADIOF_ALLOCINBUFFER
  175.       This flags cause the function to allocate an input buffer.
  176.       If not set (e.g. when working from memory) the fields
  177.             xio_InBufferSize
  178.             xio_InBuffer
  179.           must be set after this function call.
  180.     XADIOF_ALLOCOUTBUFFER
  181.       This function causes the system to allocate an output buffer.
  182.       If not set (e.g. when working from memory) the fields
  183.             xio_OutBufferSize
  184.             xio_OutBuffer
  185.           must be set after this function call.
  186.     XADIOF_NOINENDERR
  187.       The function xadIOGetChar() does not produce an error at buffer
  188.       end, but inserts 0 characters as long as needed.
  189.     XADIOF_NOOUTENDERR
  190.       The function xadIOPutChar() does not check the size of output
  191.       stream, but outputs data anyway. This is required when the
  192.       output file size is not know before. Note that this has problems,
  193.       when extracting to memory, as the function xadIOWriteBuf() gets
  194.       called if buffer is full and needs to be flushed.
  195.     XADIOF_NOCRC16
  196.       Do not calculate standard CRC16. Saves some time. The CRC is
  197.       calculated in xadIOWriteBuf() function.
  198.     XADIOF_NOCRC32
  199.       Do not calculate standard CRC32. Saves some time. The CRC is
  200.       calculated in xadIOWriteBuf() function.
  201.     XADIOF_COMPLETEOUTFUNC
  202.       The supplied output-function does complete output itself. This maybe
  203.       necessary sometimes. Normally it only works with the output buffer
  204.       and lets xadWriteBuf() do the output.
  205.  
  206.     Although the cannot be passed as flags directly, here the description
  207.     of the missing flags. These are set by other functions to supply
  208.     status information:
  209.     XADIOF_LASTINBYTE
  210.       Is set in case the last input byte was read.
  211.     XADIOF_LASTOUTBYTE
  212.       Is set in case the last output byte was writen.
  213.     XADIOF_ERROR
  214.       Is set in case an error occured. This flag reduces the need to do
  215.       an additional check for error conditions.
  216.  
  217.     INPUT
  218.         flags         - XADIOF_xxx flags
  219.         ai            - Communication structure for buffer reads and stuff
  220.             like that. Maybe zero in case the xioIOGetChar() and
  221.             xadIOWriteBuf() functions need not access input or
  222.             output buffers.
  223.     xadMasterBase - The base library pointer.
  224.  
  225.     RESULT
  226.         ptr           - Pointer to xadInOut structure or zero for error.
  227.  
  228.     SEE ALSO
  229.         xadIO.h, xadIO.c, xadIOGetChar(), xadIOPutChar(), xadIOWriteBuf(),
  230.         xadFreeObjectA()
  231.  
  232. xadIO/xadIOWriteBuf                                       xadIO/xadIOWriteBuf
  233.  
  234.     NAME
  235.         xadIOWriteBuf - Flushed output buffer
  236.  
  237.     SYNOPSIS
  238.         LONG xadIOWriteBuf(struct xadInOut *io)
  239.  
  240.     FUNCTION
  241.     This function is called from xadIOPutChar() in case the buffer is
  242.     full AND a new byte needs to be written! This is essential! It means
  243.     this function is never called if size of output buffer and output
  244.     file size are equal.
  245.  
  246.     It needs to be called directly after the sucessful extraction to flush
  247.     partial buffers.
  248.  
  249.     This behaviour allows to extract to memory directly without ever
  250.     calling this function.
  251.  
  252.     It also calculates CRC16 and CRC32 values and allows to call special
  253.     output functions processing the buffer. These functions may takeover
  254.     the complete output process (althought not recommended).
  255.  
  256.     INPUT
  257.         io  - the xadInOut structure
  258.  
  259.     RESULT
  260.         err - an XAD error code
  261.  
  262.     SEE ALSO
  263.         xadIO.h, xadIO.c, xadIOPutChar(), xadIOWriteBuf()
  264.  
  265. xadIO/xio_GetFunc                                           xadIO/xio_GetFunc
  266.  
  267.     NAME
  268.         xio_GetFunc - Gets one character
  269.  
  270.     SYNOPSIS
  271.         UBYTE xio_GetFunc(struct xadInOut *io)
  272.  
  273.         XADINOUTGET xio_GetFunc
  274.  
  275.     FUNCTION
  276.     This function reads one character from source. It is called through
  277.     the io-structure using the macro xadIOGetChar(). The standard function
  278.     is assigned by xadIOAlloc() and maybe replaced by own functions.
  279.  
  280.     Replacements need to take care of following:
  281.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  282.       set in case of errors.
  283.     - If XADIOF_NOINENDERR is not set the error code XADERR_DECRUNCH is
  284.       returned if no more bytes are available, else zero bytes are
  285.       returned.
  286.     - The function io->xio_InFunc must be called after complete buffer
  287.       reads.
  288.     - The field io->xio_InBufferPos needs to be used and set correctly.
  289.     - The field io->xio_InSize is decreased for every read byte.
  290.     - The Flag XADIOF_LASTINBYTE is set for last read byte.
  291.  
  292.     - The field io->xio_GetFuncPrivate is for private use.
  293.  
  294.     INPUT
  295.         io  - the xadInOut structure
  296.  
  297.     RESULT
  298.         res - one byte read from source
  299.  
  300.     SEE ALSO
  301.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar()
  302.  
  303. xadIO/xio_InFunc                                             xadIO/xio_InFunc
  304.  
  305.     NAME
  306.         xio_InFunc - Input processing buffer
  307.  
  308.     SYNOPSIS
  309.         void xio_InFunc(struct xadInOut *io, ULONG size)
  310.  
  311.         XADINOUTFUNC xio_InFunc
  312.  
  313.     FUNCTION
  314.     This function allows the preprocess the input buffer. This maybe used
  315.     to call decryption routines or checksum algorithms. It gets the
  316.     xadInOut structure and the buffer size as argument.
  317.     It is allow to modify the contents of xio_InBuffer from position zero
  318.     until passed size. Nothing else except the private pointer maybe
  319.     changed.
  320.     It does not support buffer expansion or size changes.
  321.  
  322.     This function is called from xadIOGetChar() or xio_GetFunc() after
  323.     reading a new buffer.
  324.  
  325.     Replacements need to take care of following:
  326.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  327.       set in case of errors.
  328.  
  329.     - The field io->xio_InFuncPrivate is for private use.
  330.  
  331.     INPUT
  332.         io   - the xadInOut structure
  333.         size - the input buffer size
  334.  
  335.     RESULT
  336.         none
  337.  
  338.     SEE ALSO
  339.         xadIO.h, xadIO.c, xadIOGetChar(), xio_GetFunc()
  340.  
  341. xadIO/xio_OutFunc                                           xadIO/xio_OutFunc
  342.  
  343.     NAME
  344.         xio_OutFunc - Output processing buffer
  345.  
  346.     SYNOPSIS
  347.         void xio_OutFunc(struct xadInOut *io, ULONG size)
  348.  
  349.         XADINOUTFUNC xio_OutFunc
  350.  
  351.     FUNCTION
  352.     This function allows the preprocess the output buffer. This maybe used
  353.     to call decryption routines or checksum algorithms. It gets the
  354.     xadInOut structure and the buffer size as argument.
  355.     It is allow to modify the contents of xio_OutBuffer from position zero
  356.     until passed size. Nothing else except the private pointer maybe
  357.     changed.
  358.  
  359.     This function is called from xadIOWriteBuf() before writing the
  360.     buffer. If the flag XADIOF_COMPLETEOUTFUNC is set, this function
  361.     also needs to store the output buffer using xadHookAccess().
  362.  
  363.     Replacements need to take care of following:
  364.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  365.       set in case of errors.
  366.  
  367.     - The field io->xio_OutFuncPrivate is for private use.
  368.  
  369.     INPUT
  370.         io   - the xadInOut structure
  371.         size - the output buffer size
  372.  
  373.     RESULT
  374.         none
  375.  
  376.     SEE ALSO
  377.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOWriteBuf(), xadHookAccess()
  378.  
  379. xadIO/xio_PutFunc                                           xadIO/xio_PutFunc
  380.  
  381.     NAME
  382.         xio_PutFunc - Stores (one) character in output stream
  383.  
  384.     SYNOPSIS
  385.         UBYTE xio_PutFunc(struct xadInOut *io, UBYTE c)
  386.  
  387.         XADINOUTPUT xio_PutFunc
  388.  
  389.     FUNCTION
  390.     This function stores (one) character into destination. It is called
  391.     through the io-structure using the macro xadIOPutChar(). The standard
  392.     function is assigned by xadIOAlloc() and maybe replaced by own
  393.     functions.
  394.  
  395.     This function maybe used to do inline decompression (e.g. RLE) and
  396.     thus not necessary stores the passed byte or may store more than
  397.     one byte.
  398.  
  399.     Replacements need to take care of following:
  400.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  401.       set in case of errors.
  402.     - If XADIOF_NOOUTENDERR is not set the error code XADERR_DECRUNCH is
  403.       returned if no more bytes can be stored, else the additional bytes
  404.       are stored.
  405.     - The field io->xio_OutBufferPos needs to be used and set correctly.
  406.     - The field io->xio_OutSize is decreased for every read byte.
  407.     - The Flag XADIOF_LASTOUTBYTE is set for last read byte.
  408.     - The passed byte needs to be returned as result!
  409.     - If the buffer is full and a new byte needs to be stored
  410.       xadIOWriteBuf() needs to be called. Never before!
  411.  
  412.     - The field io->xio_PutFuncPrivate is for private use.
  413.  
  414.     INPUT
  415.         io  - the xadInOut structure
  416.         c   - the byte to store or process
  417.  
  418.     RESULT
  419.         res - the byte passed as argument
  420.  
  421.     SEE ALSO
  422.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOPutChar(), xadIOWriteBuf()
  423.  
  424.  
  425.  
  426.